iT邦幫忙

2021 iThome 鐵人賽

DAY 29
0

基本上 side project 所有的工作在這邊告一段落,現在要來最重要的收尾步驟,就是寫 readme

為什麼要寫 readme

寫 readme 是很多工程師很懶惰做的事情,其中也包含我。其中不想寫 readme 的原因自己分析有以下幾項:

  1. 覺得忙來忙去,終於把程式寫好了,好累喔,之後有空再來寫,然後就沒有之後了
  2. 覺得精華都在程式碼之中,與其看 readme 不如去看程式碼
  3. 文學素養匱乏,寫程式時滿腹的想法與靈感,寫介紹時,卻一個字都擠不出來
  4. 不知道怎麼好好介紹自己辛苦寫出來的專案

以上是自己分析自己懶得寫的原因。不過自己心知肚明,不寫 readme 的話,根本不會有人知道這個專案在做什麼的。

假設是自己寫興趣的專案的話:

如果沒有寫 readme ,身為一名同為開發人員的我,看到一個有趣的專案,readme 是空白或制式的,可能就會有點懶得點進去了。或是無法一時之間,從程式碼看出東西又沒有介紹的話,可能也就會關掉了。這樣就會讓自己辛辛苦苦寫出來的專案無法讓人知道,差了最後一哩路,非常可惜

假設想要拿來求職的話:

如果沒有寫 readme ,因為招募人員不一定是開發人員,有時候都會是人資或是非工程師看不懂程式碼的人來尋找人才,唯一能讓他們了解你的專案快樂又厲害的方法就是把 readme 寫好,讓不懂的人也能知道這個專案在做什麼,有什麼厲害的地方。

而這個恰巧對工程師自身來說,也是一個很好的練習機會。如何遇到內行的人說行話,遇到外行的人,用各種類比或簡單的方式說到對方能懂。這個也是在工作場合乃至人生當中,常常會遇到的事情,所以藉著這個機會,來練習一下自己的溝通技巧,這也是非常重要的。

readme 撰寫的範例

以下是筆者個人摸索出來 readme 的一些寫法。

一定要有圖片

現在很多人喜歡看圖文或是懶人包,不喜歡看文字,雖然這不是很好的現象,但是不可諱言,與其看了一大堆文字描述,還想像不出畫面,如果搭配圖片來解說一定清楚多了

闡述自己的理念與想法

闡述理念和想法是筆者認為最重要的一項。畢竟寫再多的程式碼就只是一種理念實現的工具。最重要的是想要達成什麼目的或是解決什麼困擾。這個才是每個開發人員撰寫程式碼最重要的目的。

所以述說自己的理念與想法,就是告訴讀者,想要做什麼,你才會動手去做這些事情。

像是筆者想要發揚「原子習慣」的理念,因為動手打造了一個符合原子習慣理念的打卡工具

最後介紹自己是用什麼技術來實現你的想法

既然是工程師寫的專案,不免俗地還是要列出,自己使用了什麼技術來實現想法,以筆者的專案為例,在這一系列的文章當中,筆者使用以下工具與框架

  • angular : 建立前端架構
  • rxjs : 處理非同步的問題
  • bootstrap : 排版
  • nebular : UI框架
  • nx : monorepo的建構工具
  • nestjs :建立後端架構
  • firebase : 儲存檔案與處理資料庫資料
  • line message api : 與line 做溝通連結

讓懂得開發人員可以看門道,不懂的人也可以記住這些關鍵字,這個就是寫 readme 的妙用


上一篇
DAY28 - 來試試看 line notify吧
下一篇
DAY30 - side project 的尾巴,反省與展望
系列文
做一個面試官無法拒絕的sideproject,當一個全能的前端30
圖片
  直播研討會
圖片
{{ item.channelVendor }} {{ item.webinarstarted }} |
{{ formatDate(item.duration) }}
直播中

尚未有邦友留言

立即登入留言